/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (the "License"); you may not use this file except in compliance with
 *  the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.apache.coyote;

import org.apache.tomcat.util.net.AbstractEndpoint;

import java.util.concurrent.Executor;


/**
 * Connector中的组件之一:
 * 主要负责对不同通信协议的解析，如Http协议与AJP协议，ajp协议用的比较少，这里我们只分析HTTP协议即可
 * 其中的组件：
 * 1. Endpoint：是接收端的抽象，实际上是对不同接收请求的方式的抽象，主要体现在IO方式的不同，比如BIO(JIoEndpoint)、NIO(NioEndpoint)、APR(AprEndpoint)
 * 见AbstractProtocol类中的endpoint，它的主要逻辑在org.apache.tomcat.util.net.AbstractEndpoint中定义，而实际上真正接收客户端连接的是AbstractEndpoint类中的Acceptor组件
 *
 * 2. Executor：处理客户端请求的线程池，这个连接池可能是与Service组件共享的线程池，也可以是自己独有的线程池
 *
 * 3. Processor：处理客户端请求的处理器，不同协议和不同的IO方式都有不同的处理器，所以存在不同类型的处理器，处理的逻辑主要在
 * org.apache.coyote.Processor接口中定义
 *
 *
 *
 * ProtocolHandler 有一个抽象实现类AbstractProtocol, AbstractProtocol 下面分了三种类型： Ajp 、HTTP 和Spdy 。
 * Ajp是Apache JServ Protocol 的缩写， Apache 的定向包协议，主要用于与前端服务器（如Apache ）进行通信，它是长连接，不需要每次通信都重新建立连接，这样就节省了开销；
 * Spdy 协议Google开发的协议，作用类似HTTP ，比HTTP 效率高，不过这只是Google 制定的企业级协议，使用并不广泛，而且在HTTP/2 协议中已经包含了Spdy 所提供的优势，
 * 所以Spdy 协议平常很少使用，不过Tomcat 提供了支持

 *
 * Abstract the protocol implementation, including threading, etc.
 *
 * This is the main interface to be implemented by a coyote protocol.
 * Adapter is the main interface to be implemented by a coyote servlet
 * container.
 *
 * @author Remy Maucherat
 * @author Costin Manolache
 * @see AbstractProtocol#endpoint
 * @see AbstractEndpoint
 * @see org.apache.coyote.ProtocolHandler#getExecutor
 * @see Processor
 */
public interface ProtocolHandler {

    /**
     * Return the adapter associated with the protocol handler.
     * @return the adapter
     */
    public Adapter getAdapter();


    /**
     * The adapter, used to call the connector.
     *
     * @param adapter The adapter to associate
     */
    public void setAdapter(Adapter adapter);


    /**
     * The executor, provide access to the underlying thread pool.
     *
     * @return The executor used to process requests
     */
    public Executor getExecutor();


    /**
     * Initialise the protocol.
     *
     * @throws Exception If the protocol handler fails to initialise
     */
    public void init() throws Exception;


    /**
     * Start the protocol.
     *
     * @throws Exception If the protocol handler fails to start
     */
    public void start() throws Exception;


    /**
     * Pause the protocol (optional).
     *
     * @throws Exception If the protocol handler fails to pause
     */
    public void pause() throws Exception;


    /**
     * Resume the protocol (optional).
     *
     * @throws Exception If the protocol handler fails to resume
     */
    public void resume() throws Exception;


    /**
     * Stop the protocol.
     *
     * @throws Exception If the protocol handler fails to stop
     */
    public void stop() throws Exception;


    /**
     * Destroy the protocol (optional).
     *
     * @throws Exception If the protocol handler fails to destroy
     */
    public void destroy() throws Exception;


    /**
     * Requires APR/native library
     *
     * @return <code>true</code> if this Protocol Handler requires the
     *         APR/native library, otherwise <code>false</code>
     */
    public boolean isAprRequired();
}
